home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / utilities / pu017.dms / pu017.adf / Screens / Screens.doc < prev    next >
Text File  |  1990-01-30  |  20KB  |  609 lines
  1. 1    SCREENS
  2.  
  3. 1.1  INTRODUCTION
  4.  
  5. The screen is the foundation of Intuition's display. It
  6. determines how many colours you can use, what kind of colours,
  7. what resolution etc. Every window, gadget, icon, drawing is
  8. connected to a screen. Moving that screen, and you are also
  9. moving the objects on it. You may have several screens running
  10. at the same time, and you may combine different screens (with
  11. their own individual resolutions, colours, etc) on the same
  12. display.
  13.  
  14.  
  15.  
  16. 1.2  DIFFERENT TYPES OF SCREENS
  17.  
  18. When you are going to use a screen you first need to decide if
  19. you want to use a Standard (Workbench) Screen or if you want to
  20. use a Screen which you yourself has customized (Custom Screens).
  21.  
  22. Workbench Screen:
  23.   This is Intuition's standard screen. It is a four-colour,
  24.   high-resolution screen. 
  25.  
  26. Custom Screens:
  27.   When you want a screen with your own display mode you should
  28.   use a Custom Screen. You can then decide yourself how many
  29.   colours you want, what colours, resolution, size etc.
  30.  
  31. If your program should use a high-resolution screen, and four
  32. colours is enough, you are advised to use the Workbench Screen.
  33. This will save a lot of memory (no memory allocated for a
  34. Custom Screen), and allows the user to have several programs
  35. running on the same display. On the other hand, if you want
  36. more colours or want to use a different resolution/display-mode
  37. you should use a Custom Screen.
  38.  
  39.  
  40.  
  41. 1.3  WORKBENCH SCREEN
  42.  
  43. Workbench Screen is a high-resolution (640 pixels wide), four
  44. colour screen. It is either 200 or 256 lines high depending on
  45. if you have a NTSC (American) or a PAL (European) computer.
  46. (400/512 lines if you have an Interlaced display.)
  47.  
  48. The Workbench Screen will automatically open if there does not
  49. exist any other screens. If you do not want the Workbench
  50. Screen, and need a lot of memory, you can try to close it,
  51. CloseWorkBench(). Remember to reopen it when your program has
  52. finished, OpenWorkBench().
  53.  
  54. You are advised to always call the function OpenWorkBench()
  55. when your program exits, even if you have not closed it
  56. yourself. Another program may have closed it because of
  57. shortage of memory, and when your program is finished there
  58. may exist enough memory. This will make the Workbench Screen
  59. available as much as possible.
  60.  
  61.  
  62.  
  63. 1.4  CUSTOM SCREENS
  64.  
  65. If you are going to use a Custom Screen you need to initialize
  66. a structure (NewScreen) with your requirements. You also need
  67. to open the screen yourself by calling the function
  68. OpenScreen().
  69.  
  70. Here is a list of some important decisions you need to make
  71. before you can open the screen:
  72.  
  73.  
  74.   
  75. 1.4.1  RESOLUTION
  76.  
  77. You can either have a high-resolution or a low-resolution
  78. screen. A high resolution screen is 640 pixels wide, while a
  79. low-resolution screen is only 320 pixels wide. However, a high-
  80. resolution screen may only have a depth of up to 4 (maximum 16
  81. colours), while a low-resolution screen may have a depth of up
  82. to 5 (32 colours), or even 6 if using some special display
  83. modes.
  84.  
  85.  
  86.  
  87. 1.4.2  DEPTH
  88.  
  89. A screen's depth means how many bits are used for every pixel.
  90. The more bits the more combinations/colours:
  91.  
  92. Depth   Number of colours   Colour register number
  93. --------------------------------------------------
  94.   1             2                   0 -  1
  95.   2             4                   0 -  3
  96.   3             8                   0 -  7
  97.   4            16                   0 - 15
  98.   5            32                   0 - 31  (Only low-res)
  99.  
  100. A low resolution screen may even have a depth of 6 if using
  101. some special display modes (HAM / EXTRA HALFBRIGHTE ).
  102.  
  103. Each colour may be picked out of a 4096 colour palette. Once
  104. you have opened your Custom Screen you may change the colours
  105. by calling the graphics function SetRGB4().
  106.  
  107.  
  108.  
  109. 1.4.3  INTERLACED
  110.  
  111. An Interlaced screen can be 400/512 lines while a Non-
  112. Interlaced screen can only be 200/256 lines. You are recommended
  113. to use a Non-Interlaced screen if possible, since an Interlaced
  114. display appear to "flicker" if the user does not have a special
  115. high-phosphor-persistence monitor. (99% of the users do not
  116. have it.)
  117.  
  118. The monitor normally draws the display 50 times per second. If
  119. you are using an Interlaced screen the Amiga will only draw
  120. every second line first, and will the next time draw the
  121. remaining lines. This is why an Interlaced display appear to
  122. "flicker". You can eliminate much of the disturbing effects if
  123. you are using colours with low contrasts, black and grey
  124. instead of black and white for example.
  125.  
  126.  
  127.  
  128. 1.4.4  HAM AND EXTRA HALFBRIGHTE
  129.  
  130. If you have a low-resolution, six bitplanes (Depth 6) screen
  131. you can either use the special HAM mode, or the Extra
  132. Halfbrighte mode. HAM allows you to display all 4096 colours
  133. at the same time, but has some restrictions, and is
  134. complicated to use. Extra Halfbrighte gives you 32 extra
  135. colours, which are the same as the first 32 colours, but are
  136. a bit brighter.
  137.  
  138. Both HAM and Extra Halfbrighte is using a lot of memory/
  139. processing time, and is therefore not commonly used.
  140.  
  141.  
  142.  
  143. 1.4.5  DUAL PLAYFIELDS
  144.  
  145. Dual Playfields allows you to have two screens on top of each
  146. other. The top screen can then be transparent in some places
  147. (colour register 0) to show the bottom screen.
  148.  
  149.  
  150.  
  151. 1.4.6  FONTS
  152.  
  153. You can specify a default font which will be used, if nothing
  154. else is specified, to draw the text on the screen. The system's
  155. default font is called Topaz and exist in two sizes:
  156.  
  157. TOPAZ_SIXTY  : 9 lines tall, 64/32 characters per line.
  158. TOPAZ_EIGHTY : 8 lines tall, 80/40 characters per line.
  159.  
  160. This font is built in the Amiga, and is therefore always
  161. available. (See chapter 3 GRAPHICS for more information.)
  162.  
  163.  
  164.  
  165. 1.4.7  SIZE AND POSITION
  166.  
  167. The top of your screen does not need to be at the top of the
  168. display. You may open several screens and position them under
  169. each other. If you are, for example, designing an adventure
  170. game, you can have a low-resolution 32 colour screen at the top
  171. of the display (showing some nice pictures), and have a high-
  172. resolution 2 colour screen at the bottom of the display (showing
  173. the text).
  174.  
  175. (Remember that the user later can drag the screens up or down
  176. himself.) 
  177.  
  178. The width of the screen should be either 320 (low-resolution)
  179. or 640 pixels (high-resolution).
  180.  
  181. The height may be anything between 1 - 200/256 lines on an Non-
  182. Interlaced screen, and between 1 - 400/512 lines on an
  183. Interlaced display.
  184.  
  185.  
  186.  
  187. 1.4.8  TITLE
  188.  
  189. On top of each screen (on the "drag bar") there exist a screen
  190. title. There exist two kinds of titles:
  191.   - The default title, which is specified in the NewScreen
  192.     structure.
  193.   - A "current" title which is the same as the title of the
  194.     current active window. (See chapter 2 WINDOWS for more
  195.     information.)
  196.  
  197.  
  198.  
  199. 1.4.9  GADGETS
  200.  
  201. For the moment you are not allowed to attach any custom gadgets
  202. to a screen. (See chapter 4 GADGETS for more information about
  203. gadgets.)
  204.  
  205.  
  206.  
  207. 1.5  INITIALIZE A CUSTOM SCREEN
  208.  
  209. Before you can open a custom screen you need to initialize a
  210. NewScreen structure which look like this:
  211.  
  212. struct NewScreen
  213. {
  214.   SHORT LeftEdge, TopEdge, Width, Height, Depth;
  215.   UBYTE DetailPen, BlockPen;
  216.   USHORT ViewModes;
  217.   USHORT Type;
  218.   struct TextAttr *Font;
  219.   UBYTE *DefaultTitle;
  220.   struct Gadget *Gadgets;
  221.   struct BitMap *CustomBitMap;
  222. };
  223.  
  224. LeftEdge:     Initial x position of the screen. Should always
  225.               be 0.
  226.  
  227. TopEdge:      Initial y position of the screen.
  228.  
  229. Width:        If it is a low-resolution screen it should be
  230.               320, otherwise 640.
  231.  
  232. Height:       If it is a Non-Interlaced screen it can be
  233.               anything between 1 - 200/256, otherwise 1 -
  234.               400/512.
  235.  
  236. Depth:        1-4 if high-resolution, otherwise 1-6.
  237.  
  238. DetailPen:    The colour register used to draw the text with.
  239.  
  240. BlockPen:     The colour register used for block fills etc.
  241.  
  242. ViewModes:    You can use none or some of the flags. If you set
  243.               more than one flag you put a "|" between them.
  244.               (You are not allowed to set the HIRES flag
  245.               together with the DUALPF or HAM flag, and you
  246.               can not have DUALPF at the same time as HAM.)
  247.  
  248.                 HIRES      Set this flag if you want a high-
  249.                            resolution screen. (The default is
  250.                            low-resolution.)
  251.  
  252.                 INTERLACE  Set this flag if you want an
  253.                            Interlaced screen. (The default
  254.                            is Non-Interlaced)
  255.  
  256.                 SPRITES    Set this flag if you are going to
  257.                            use sprites in your display.
  258.  
  259.                 DUALPF     Set this flag if you want to use the
  260.                            Dual Playfields Mode.
  261.  
  262.                 HAM        Set this flag if you want to use the
  263.                            Hold And Modify Mode.
  264.  
  265. Type:         Should be CUSTOMSCREEN. You can also set the
  266.               CUSTOMBITMAP flag if you want the screen to use
  267.               your own declared and initialized BitMap. (See
  268.               chapter 2 WINDOWS for more information about
  269.               Custom BitMaps.)
  270.  
  271. Font:         A pointer to an already initialized TextAttr
  272.               structure. The screen will use it as the default
  273.               font. (See chapter 3 GRAPHICS for more information
  274.               about fonts.) Set to NULL if you want to use the
  275.               current default font.
  276.  
  277. DefaultTitle: A pointer to a text string which will be used as
  278.               "default" title.
  279.  
  280. Gadgets:      Not used for the moment. Set to NULL.
  281.  
  282. CustomBitMap: If you want to use your own BitMap you should
  283.               give this field a pointer to the BitMap structure
  284.               which you have declared, and initialized yourself.
  285.               Remember to set the CUSTOMBITMAP flag in the Type
  286.               variable. However, if you want Intuition to take
  287.               care of the BitMap, set this field to NULL. (See
  288.               chapter 2 WINDOWS for more information about
  289.               Custom BitMaps.)
  290.  
  291.  
  292.  
  293. 1.6  OPEN A CUSTOM SCREEN
  294.  
  295. Once you have declared and initialized the NewScreen structure,
  296. you can call the function OpenScreen() which will open your
  297. Custom Screen. When your screen has been opened you can, if you
  298. have allocated memory for the NewScreen structure, deallocate
  299. it since you do not need the structure any more.
  300.  
  301. This is how you call the OpenScreen() function:
  302.  
  303. my_screen = OpenScreen( &my_new_screen ); 
  304.  
  305. my_screen has been declared as:
  306.   struct Screen *my_screen;
  307.  
  308. my_new_screen has been declared as:
  309.   struct NewScreen my_new_screen;
  310.   and has been initialized with your requirements.
  311.  
  312.  
  313. OpenScreen() will return a pointer to a Screen structure, else
  314. NULL if it could not open the screen (for example, not enough
  315. memory). Remember to check what OpenScreen() returned!
  316.  
  317. if( my_screen==NULL )
  318. {
  319.   /* PANIC! Could not open the screen */
  320. }
  321.  
  322.  
  323.  
  324. 1.7  SCREEN STRUCTURE
  325.  
  326. Once you have opened the screen you will receive a pointer to
  327. a Screen structure which look like this:
  328.  
  329. struct Screen
  330. {
  331.   struct Screen *NextScreen;    /* Pointer to the next */
  332.                                 /* screen, or NULL. */
  333.   struct Window *FirstWindow;   /* Pointer to the first */
  334.                                 /* Window on this screen. */
  335.   SHORT LeftEdge, TopEdge;      /* Position of the screen. */
  336.   SHORT Width, Height;          /* Size of the screen. */
  337.   SHORT MouseY, MouseX;         /* Mouse position relative */
  338.                                 /* to the top left corner */
  339.                                 /* of the screen. */
  340.   USHORT Flags;                 /* The selected flags. */
  341.   UBYTE *Title;                 /* The screen's Current title. */
  342.   UBYTE *DefaultTitle;          /* The screen's Default title. */
  343.  
  344.   BYTE BarHeight, BarVBorder,
  345.        BarHBorder, MenuVBorder,
  346.        MenuHBorder;
  347.   BYTE WBorTop, WBorLeft,
  348.        WBorRight, WBorBottom;
  349.  
  350.   struct TextAttr *Font;        /* The screens default font. */
  351.   struct ViewPort ViewPort;     /* The screen's ViewPort etc: */
  352.   struct RastPort RastPort;
  353.   struct BitMap BitMap;
  354.   struct Layer_Info LayerInfo;
  355.   struct Gadget *FirstGadget;
  356.   UBYTE DetailPen, BlockPen;
  357.   USHORT SaveColor0;
  358.   struct Layer *BarLayer;
  359.   UBYTE *ExtData;
  360.   UBYTE *UserData;
  361. };
  362.  
  363. You will probably not use this structure a lot, but some
  364. variables/structures can be useful later on. When you are, for
  365. example, using the function SetRGB4(). More about this later.
  366.  
  367.  
  368.  
  369. 1.8  FUNCTIONS
  370.  
  371. Here are some common functions which will effect screens:
  372.  
  373. OpenScreen()
  374.  
  375.   This function will open a Custom Screen with your
  376.   requirements.
  377.  
  378.   Synopsis:      my_screen = OpenScreen( my_new_screen );
  379.   
  380.   my_screen:     (struct Screen *) Pointer to a Screen
  381.                  structure. It will point to your newly opened
  382.                  screen or be equal to NULL if the screen could
  383.                  not be opened.
  384.  
  385.   my_new_screen: (struct NewScreen *) Pointer to a NewScreen
  386.                  structure which contains your preferences.
  387.  
  388.  
  389. CloseScreen()
  390.  
  391.   This function will close a Custom Screen which you have
  392.   previously opened.
  393.   
  394.   Synopsis:      CloseScreen( my_screen );
  395.   
  396.   my_screen:     (struct Screen *) Pointer to an already opened
  397.                  screen.
  398.  
  399.   All windows (See chapter 2 WINDOWS for more information) on
  400.   your Screen MUST have been closed before you may close the
  401.   screen. If you close a window after the screen has been
  402.   closed, the system will crash. (Not recommended.)
  403.   
  404.   If there does not exist any more screens when you close
  405.   yours, Intuition will automatically reopen the Workbench
  406.   Screen.
  407.  
  408.  
  409. MoveScreen()
  410.  
  411.   This function will move the screen. For the moment you may
  412.   only move it vertically.
  413.  
  414.   Synopsis:      MoveScreen( my_screen, delta_x, delta_y );
  415.  
  416.   my_screen:     (struct Screen *) Pointer to the screen which
  417.                  you want to move.
  418.  
  419.   delta_x:       (long) Number of pixels which the screen
  420.                  should move horizontally. For the moment you
  421.                  may not move a screen horizontally, set it
  422.                  therefore to 0.
  423.  
  424.   delta_y:       (long) Number of lines which the screen should
  425.                  move vertically.
  426.  
  427.  
  428. ScreenToBack()
  429.  
  430.   This will move the screen behind all other screens.
  431.   
  432.   Synopsis:      ScreenToBack( my_screen );
  433.  
  434.   my_screen:     (struct Screen *) Pointer to the screen which
  435.                  you want to move.
  436.  
  437.  
  438. ScreenToFront()
  439.  
  440.   This will move the screen in front of all other screens.
  441.   
  442.   Synopsis:      ScreenToFront( my_screen );
  443.  
  444.   my_screen:     (struct Screen *) Pointer to the screen which
  445.                  you want to move.
  446.  
  447.  
  448. ShowTitle()
  449.  
  450.   This function will make the screen's Title appear above or
  451.   behind any Backdrop Windows (See chapter 2 WINDOWS for more
  452.   information about Backdrop Windows). (The screen's title
  453.   appear always behind normal windows.)
  454.  
  455.   Synopsis:      ShowTitle( my_screen, show_it );
  456.  
  457.   my_screen:     (struct Screen *) Pointer to the screen.
  458.  
  459.   show_it:       (long) A boolean value which can be:
  460.                  TRUE:  The title will be in front of any
  461.                         Backdrop Windows, but behind any
  462.                         other windows.
  463.                  FALSE: The Title will be behind any windows.
  464.  
  465.  
  466. OpenWorkBench()
  467.  
  468.   This function will try to open the Workbench Screen if there
  469.   exist enough memory.
  470.   
  471.   Synopsis:      result = OpenWorkBench();
  472.   
  473.   result:        (long) A boolean value which tell us if the
  474.                  Workbench Screen has been (or already was)
  475.                  opened (TRUE), or not (FALSE).
  476.  
  477.  
  478. CloseWorkBench()
  479.  
  480.   This function will try to close the Workbench Screen if
  481.   possible. If any other programs is using the Workbench
  482.   Screen, the function can not close it. Closing the Workbench
  483.   will free some memory, and can therefore be used if your
  484.   program needs more memory.
  485.   
  486.   (Remember to reopen the Workbench Screen when your program
  487.   terminates.)
  488.  
  489.   Synopsis:      result = CloseWorkBench();
  490.   
  491.   result:        (long) A boolean value which tell us if the
  492.                  Workbench screen has been (or already was)
  493.                  closed (TRUE), or not (FALSE).
  494.  
  495.  
  496. WBenchToBack()
  497.  
  498.   This will move the Workbench Screen behind all other screens.
  499.   
  500.   Synopsis:      result = WBenchToBack();
  501.  
  502.   result:        (long) A boolean value which is TRUE if the
  503.                  Workbench screen was open, or FALSE it it was
  504.                  not.
  505.  
  506.  
  507. WBenchToFront()
  508.  
  509.   This will move the Workbench Screen in front of all other
  510.   screens.
  511.  
  512.   Synopsis:      result = WBenchToFront();
  513.  
  514.   result:        (long) A boolean value which is TRUE if the
  515.                  Workbench screen was open, or FALSE it it was
  516.                  not.
  517.  
  518.  
  519. SetRGB4()
  520.  
  521.   This function allows you to change your screen's colours.
  522.   Each colour may be picked out of a 4096 colour palette. (16
  523.   levels of red, 16 levels of green and 16 levels of blue;
  524.   16*16*16 = 4096.)
  525.  
  526.   IMPORTANT! Before you may use this function you must have
  527.   opened the Graphics Library. (All other functions are in the
  528.   Intuition Library.) (See chapter 0 INTRODUCTION for more
  529.   information.)
  530.  
  531.   Synopsis:   SetRGB4( viewport, register, red, green, blue );
  532.            
  533.   viewport:   (struct ViewPort *) Pointer to a ViewPort which
  534.               colour registers we are going to change. We can
  535.               find the screen's ViewPort in the Screen
  536.               structure. (If my_screen is a pointer to a Screen
  537.               structure, this will get us a pointer to that
  538.               screen's ViewPort: &my_screen->ViewPort)
  539.  
  540.   register:   (long) The colour register you want to change.
  541.               The screen's Depth decides how many colour
  542.               registers the screen have:
  543.  
  544.               Depth  Colour Registers
  545.               -----------------------
  546.               1      0 - 1
  547.               2      0 - 3
  548.               3      0 - 7
  549.               4      0 - 15
  550.               5      0 - 31
  551.               6      0 - 63
  552.  
  553.   red:        Amount of red. (0 - 15)
  554.  
  555.   green:      Amount of green. (0 - 15 )
  556.  
  557.   blue:       Amount of blue. (0 - 15 )
  558.  
  559.   Eg: SetRGB4( &my_screen->ViewPort, 2, 15, 15, 0 ); will
  560.   change colour register 2 to be light yellow. (Red and green
  561.   together will be yellow.)
  562.  
  563.  
  564.  
  565. 1.9  EXAMPLES
  566.  
  567. We have now talked about different screens, Workbench Screen
  568. and your own Custom Screens. We have looked at how you can
  569. change the Custom Screen's display mode, resolution, depth etc,
  570. and we have described some important functions. It is now time
  571. for us to have some examples to clear up any confusions.
  572.  
  573. All Examples, both the programs as well as the source codes,
  574. are in the same directory as this document.
  575.  
  576. Example1
  577.   This program will open a low-resolution, non-Interlaced,
  578.   eight colour Custom Screen. It will display it for 30
  579.   seconds, and then close it.
  580.  
  581. Example2
  582.   Same as Example1 except that the screen will be a high-
  583.   resolution, Interlaced, 4 colour Custom Screen.
  584.  
  585. Example3
  586.   Same as Example1 except that we will use the TOPAZ_SIXTY
  587.   Italic style as default font. (See chapter 3 GRAPHICS for
  588.   more information about text styles.)
  589.  
  590. Example4
  591.   This program will open two screens, one (low-resolution 32
  592.   colours) at the top of the display, and one (high-resolution
  593.   16 colours) a bit down.
  594.  
  595. Example5
  596.   Same as Example4 except that after 10 seconds the low-
  597.   resolution screen will move down 75 lines. After another 10
  598.   seconds it will be put in front of all other screens. 10
  599.   seconds later it will move down another 75 lines. The program
  600.   will wait 10 seconds before the screens are closed and the
  601.   program exits.
  602.  
  603. Example6
  604.   This program will open a low-resolution, non-Interlaced, 4
  605.   colour Custom Screen. It will after 5 seconds start to change
  606.   the screens colours, and will after a while close the screen
  607.   and exit.
  608.  
  609.